Inks (IM: XOv)

Inside Macintosh: QuickDraw GX Programmer's Overview / Part 1 - Getting Started With QuickDraw GX: Chapter 3 - Using QuickDraw GX Objects

Inks
The ink object allows you to specify color information for your shape objects. Like all objects, ink objects have properties that you can examine and edit. When you draw a shape, QuickDraw GX examines the properties of the shape's ink object and modifies the appearance of the shape as indicated by
the values of properties of its ink object.
Figure 3-28 shows the properties of the ink object.
Figure 3-28 Ink objects and effects of their properties

The two most important properties of the ink object are the color property, which specifies the color of the shape, and the transfer mode property, which specifies how the color of the shape interacts with the background over
which the shape is drawn.
QuickDraw GX provides two useful libraries of definitions and functions that simplify the use of colors and transfer modes: the color library and the transfer mode library. You should examine these libraries to see if they provide code you might find useful for your application.

Colors
The ink object allows you to specify a shape's color. You can use the QuickDraw GX functions GXGetInkColor and GXSetInkColor to examine
and set the color property of an ink object. Similarly, the functions GXGetShapeColor and GXSetShapeColor allow you to examine and set the color property of a specified shape. If the shape shares its ink object with
other shapes, the GXSetShapeColor function makes a copy of the ink object before modifying its color property.
QuickDraw GX allows you to specify colors in a number of color spaces, including grayscale, RGB, HSV, HLS, and YIQ. See Plate 1 at the front of
this book for examples of color spaces.
To specify a color, you use the color structure, as defined by the gxColor data type. The color structure has three fields specifying

the color space in which the color is specified
the color-matching information used for converting device-independent color to color-corrected values on a particular device
the color values specifying the specific color

As an example, you can use this code to declare and initialize a color structure:
gxColor myColor;

myColor.space = gxRGBSpace;     /* color specified in RGB */
myColor.profile = nil;          /* use default color matching */
myColor.element.rgb.red = 0x8000;   /* a fair amount of red */
myColor.element.rgb.green = 0x1000; /* a touch of green */
myColor.element.rgb.blue = 0xE000;  /* a bunch of blue */
In this example, the color space is specified using the gxRGBSpace constant. QuickDraw GX provides a similar constant for each supported color space.
The color profile, which specifies color-matching information, is set to nil, which indicates that QuickDraw GX should use the default color profile.
An RGB color is specified using three color components. Each color component is specified using a color value ranging from 0x0000 to 0xFFFF. (Colors in other color spaces may be specified with a different number of components. At most, a color can have four color components.)
A special color space is the gxIndexedSpace color space. This color space indicates that the color value specifies an index into an array of predefined colors. This array is called a color set, and is represented by a color set object.
Figure 3-29 shows the color set object and its properties.
Figure 3-29 The color set object and its properties

As a simple example, you can create a color set using this code:
gxColorSet myColorSet;

gxSetColor myColorValues[] = {
   {0xFFFF, 0x0000, 0x0000, 0},     /* index 1 = red */
   {0x0000, 0xFFFF, 0x0000, 0},     /* index 2 = green */
   {0x0000, 0x0000, 0xFFFF, 0},     /* index 3 = blue */
}

myColorSet = GXNewColorSet(gxRGBSpace, 3, myColorValues);
Once you create a color set, you can specify colors using that color set. For example, this code uses the three-color color set defined previously to specify the color green:
myColor.space = gxIndexedSpace;   /* use a color set */
myColor.profile = nil;            /* default color matching */
myColor.element.indexed.set = myColorSet; /* color set */
myColor.element.indexed.index = 2;        /* index 2 = green */
For more information about colors and color-matching, see Inside Macintosh: QuickDraw GX Objects.

Transfer Modes
The transfer mode property of an ink object specifies how the color of a shape (the source color) interacts with the background over which it is drawn (the destination color). You can use the transfer mode property to make a shape opaque (only the source color shows), transparent (only the destination color shows), or translucent (the source and destination colors blend together). Transfer modes are defined using the transfer mode structure, which is defined by the gxTransferMode data type. This structure allows you a surprisingly wide range of control over how the source and destination colors are combined. See Plate 2 at the front of this book for some examples of effects you can create using transfer modes.
You can examine and modify the transfer mode property of an ink using the GXGetInkTransfer and GXSetInkTransfer functions. Similarly, you can examine and modify the transfer mode of an ink associated with a specified shape using the GXGetShapeTransfer and GXSetShapeTransfer functions.
QuickDraw GX also allows you to use alpha channels as a color component to achieve color transparency. See Plate 3 at the front of this book for a colorful example of using alpha channels. See Inside Macintosh: QuickDraw GX Objects for more information about inks, colors, and transfer modes.